'\" t
.\"     Title: IPSEC_SET_POLICY
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 02/25/2010
.\"    Manual: [FIXME: manual]
.\"    Source: [FIXME: source]
.\"  Language: English
.\"
.TH "IPSEC_SET_POLICY" "3" "02/25/2010" "[FIXME: source]" "[FIXME: manual]"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
_ipsec_set_policy \- create an IPsec policy structure from a human readable string
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <netinet6/ipsec\&.h>
.fi
.ft
.HP \w'char\ *ipsec_set_policy('u
.BI "char *ipsec_set_policy(char\ *\ " "policy" ", int\ " "len" ");"
.HP \w'int\ ipsec_get_policylen('u
.BI "int ipsec_get_policylen(char\ *\ " "buf" ");"
.HP \w'char\ *ipsec_dump_policy('u
.BI "char *ipsec_dump_policy(char\ *\ " "buf" ", char\ *\ " "delim" ");"
.SH "LIBRARY"
.PP
IPsec Policy Control Library (libipsec, \-lipsec)
.SH "DESCRIPTION"
.PP
The ipsec_set_policy(); function generates an IPsec policy specification structure,
struct
sadb_x_policy
and/or
struct
sadb_x_ipsecrequest
from a human\-readable policy specification\&. The policy specification must be given as a C string, passed in the
\fIpolicy\fR
argument and the length of the string, given as
\fIlen\fR\&. The ipsec_set_policy(); function returns pointer to a buffer which contains a properly formed IPsec policy specification structure\&. The buffer is dynamically allocated, and must be freed by using the
\fBfree\fR(3)
library function\&.
.PP
The ipsec_get_policylen(); function will returns the of the buffer which is needed when passing the specification structure to the
\fBsetsockopt\fR(2)
system call\&.
.PP
The ipsec_dump_policy(); function converts an IPsec policy structure into a human readable form\&. The
\fIbuf\fR
argument points to an IPsec policy structure,
struct
sadb_x_policy\&.
\fIdelim\fR
is a delimiter string, which is usually a blank character\&. If you set
\fIdelim\fR
to
\fBNULL\fR, a single white space is assumed\&. The ipsec_dump_policy(); function returns a pointer to dynamically allocated string\&. It is the caller\'s responsibility to free the returned pointer using the
\fBfree\fR(3)
library call\&.
.PP
A
\fIpolicy\fR
is given in the following way:
.PP
\fIdirection\fR discard
.RS 4
The
\fIdirection\fR
must be
in
or
out
and specifies which direction the policy needs to be applied, either on inbound or outbound packets\&. When the
discard
policy is selected, packets will be dropped if they match the policy\&.
.RE
.PP
\fIdirection\fR entrust
.RS 4
entrust
means to consult the security policy database (SPD) in the kernel, as controlled by
\fBsetkey\fR(8)\&.
.RE
.PP
\fIdirection\fR bypass
.RS 4
A direction of
bypass
indicates that IPsec processing should not occur and that the packet will be transmitted in clear\&. The bypass option is only available to privileged sockets\&.
.RE
.PP
\fIdirection\fR \fI \fR ipsec \fIrequest\fR \fI\&.\&.\fR \fI \fR
.RS 4
A direction of
ipsec
means that matching packets are processed by IPsec\&.
ipsec
can be followed by one or more
\fIrequest\fR
string, which is formatted as:
.PP
\fIprotocol\fR \fI \fR / \fImode\fR \fI \fR / \fIsrc\fR \fI \fR \- \fIdst\fR \fI \fR \fI/level\fR \fI \fR
.RS 4
The
\fIprotocol\fR
is one of:
ah,
esp
or
ipcomp
indicating Authentication Header, Encapsulating Security Protocol or IP Compression protocol is used\&.
.sp
The
\fImode\fR
is either
transport
or
tunnel
the meanings of both modes are described in
\fBipsec\fR(4)\&.
.sp
The
\fIsrc\fR
and
\fIdst\fR
specify the IP address, either v4 or v6, of the source and destination systems\&. The
\fIsrc\fR
always stands for the \(lqsending node\(rq and
\fIdst\fR
always stands for the \(lqreceiving node\(rq\&. When
\fIdirection\fR
is
in,
\fIdst\fR
is this local node and
\fIsrc\fR
is the remote node or peer\&. If
\fImode\fR
is
transport, both
\fIsrc\fR
and
\fIdst\fR
can be omitted\&.
.sp
The
\fIlevel\fR
must be set to one of the following:
default,
use,
require
or
unique\&.
default
means that the kernel should consult the default security policies as defined by a set of
\fBsysctl\fR(8), variables\&. The relevant
\fBsysctl\fR(8)
variables are described in
\fBipsec\fR(4)\&.
.sp
When
use
is selected a relevant security association (SA) can be used when available but is not necessary\&. If the SA is available then packets will be handled by IPsec, i\&.e\&. encrypted and/or authenticated but if an SA is not available then packets will be transmitted in the clear\&. The
use
option is not recommended because it allows for accidental mis\-configurations where encrypted or authenticated link becomes unencrypted or unauthenticated, the
require
keyword is recommended instead of
use
where possible\&. Using the
require
keyword means that a relevant SA is required, and that the kernel must perform IPsec processing on all matching packets\&.
.sp
The
unique
keyword has the same effect as
require, but adds the restriction that the SA for outbound traffic is used only for this policy\&. You may need the identifier in order to relate the policy and the SA when you define the SA by manual keying using
\fBsetkey\fR(8)\&. Put the decimal number as the identifier after the
unique
keyword in this way:
unique
:
number, where
number
must be between 1 and 32767\&.
.sp
If the
\fIrequest\fR
string is kept unambiguous,
\fIlevel\fR
and the slash prior to
\fIlevel\fR
can be omitted but you are encouraged to specify them explicitly to avoid unintended behaviors\&. If
\fIlevel\fR
is omitted, it will be interpreted as
default\&.
.RE
.RE
.PP
Note that there is a difference between the specification allowed here and in
\fBsetkey\fR(8)\&. When specifying security policies with
\fBsetkey\fR(8), neither entrust nor bypass are used\&. Refer to
\fBsetkey\fR(8)
for details\&.
.SH "EXAMPLES"
.PP
Set a policy that all inbound packets are discarded\&.
.sp
.if n \{\
.RS 4
.\}
.nf
in discard

.fi
.if n \{\
.RE
.\}
.PP
All outbound packets are required to be processed by IPsec and transported using ESP\&.
.sp
.if n \{\
.RS 4
.\}
.nf
.sp
.if n \{\
.RS 4
.\}
.nf
out ipsec esp/transport//require

.fi
.if n \{\
.RE
.\}
.sp

.fi
.if n \{\
.RE
.\}
.PP
All inbound packets are required to be authenticated using the AH protocol\&.
.sp
.if n \{\
.RS 4
.\}
.nf
.sp
.if n \{\
.RS 4
.\}
.nf
in ipsec ah/transport//require

.fi
.if n \{\
.RE
.\}
.sp

.fi
.if n \{\
.RE
.\}
.PP
Tunnel packets outbound through the endpoints at 10\&.1\&.1\&.2 and 10\&.1\&.1\&.1\&.
.sp
.if n \{\
.RS 4
.\}
.nf
out ipsec esp/tunnel/10\&.1\&.1\&.2\-10\&.1\&.1\&.1/require

.fi
.if n \{\
.RE
.\}
.SH "RETURN VALUES"
.PP
The ipsec_set_policy(); function returns a pointer to the allocated buffer containing a the policy specification if successful; otherwise a NULL pointer is returned\&.
.PP
The ipsec_get_policylen(); function returns a positive value, indicating the buffer size, on success, and a negative value on error\&.
.PP
The ipsec_dump_policy(); function returns a pointer to a dynamically allocated region containing a human readable security policy on success, and
\fBNULL\fR
on error\&.
.SH "SEE ALSO"
.PP
\fBipsec_strerror\fR(3),
\fBipsec\fR(4),
\fBsetkey\fR(8)
.SH "HISTORY"
.PP
These functions first appeared in WIDE/KAME IPv6 protocol stack kit\&.
.PP
IPv6 and IPsec support based on the KAME Project (http://www\&.kame\&.net/) stack was initially integrated into
FreeBSD 4\&.0(TM)
